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Sieve Email Filtering: Environment Extension 
Status of This Memo 


This document specifies an Internet standards track protocol for the 
Internet community, and requests discussion and suggestions for 


improvements. Please refer to the current edition of the "Internet 

Official Protocol Standards" (STD 1) for the standardization state 

and status of this protocol. Distribution of this memo is unlimited. 
Abstract 


This document describes the "environment" extension to the Sieve 
email filtering language. The "environment" extension gives a Sieve 
script access to information about the Sieve interpreter itself, 
where it is running, and about any transport connection currently 
involved in transferring the message. 


1. Introduction 


Sieve [RFC5228] is a language for filtering email messages at or 
around the time of final delivery. It is designed to be 
implementable on either a mail client or mail server. It is suitable 
for running on a mail server where users may not be allowed to 
execute arbitrary programs, such as on black box Internet Message 
Access Protocol [RFC3501] servers, as it has no user-controlled loops 
or the ability to run external programs. 


Although Sieve is intended to be independent of access protocol, mail 
architecture, and operating system, in some cases it is useful to 
allow scripts to access information about their execution context. 
The "environment" extension provides a new environment test that can 
be used to implement scripts that behave differently when moved from 
one system to another, when messages arrive from different remote 
sources or when otherwise operated in different contexts. 


2. Conventions Used in This Document 
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", “SHALL NOT", 


"SHOULD", “SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 
document are to be interpreted as described in [RFC2119]. 
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The terms used to describe the various components of the Sieve 
language are taken from Section 1.1 of [RFC5228]. 


This document refers to the ABNF productions IPv4-address-literal, 
IPv6-address-literal, and General-address-literal defined in Section 
4.1.3 of [RFC2821]. 


The location item makes use of standard terms for email service 
components. Additional information and background on these terms can 
be found in [EMAIL-ARCH]. 


3. Capability Identifiers 


The capability string associated with the extension defined in this 
document is "environment". 


4. Environment Test 


Usage: environment [COMPARATOR] [MATCH-TYPE] 
<name: string> 
<key-list: string-list> 


The environment test retrieves the item of environment information 
specified by the name string and matches it to the values specified 
in the key-list argument. The test succeeds if a match occurs. The 
type of match defaults to ":is" and the default comparator is 
"i;ascii-casemap". 


The current message is not a direct source of information for the 
environment test; the item of information specified by the name 
string is extracted from the script’s operating environment and the 
key-list argument comes from the script. 


The environment test MUST fail unconditionally if the specified 
information item does not exist. A script MUST NOT fail with an 


error if the item does not exist. This allows scripts to be written 
that handle nonexistent items gracefully. In particular, the test: 
if environment :contains "item" "" { ... } 


only succeeds if "item" is known to the implementation, and always 
succeeds if it is. 


The "relational" extension [RFC5231] adds a match type called 


"scount". The count of an environment test is 0 if the environment 
information returned is the empty string, or 1 otherwise. 
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Environment items can be standardized or vendor-defined. An IANA 
registry is defined for both types of items. Extensions designed for 
interoperable use SHOULD be defined in standards track or 
experimental RFCs. 


4.1. Initial Standard Environment Items 


The initial set of standardized environment items is as follows: 


"domain" 


"host" 


"location" 


"name" 


"phase" 


"remote-host" 


Freed 


=> 


=> 


=> 


=> 


=> 


The primary DNS domain associated with the Sieve 
execution context, usually but not always a proper 
suffix of the host name. 


The fully-qualified domain name of the host where 
the Sieve script is executing. 


Sieve evaluation can be performed at various 

different points as messages are processed. This item 
provides additional information about the type of 
service that is evaluating the script. Possible values 
are "MTA", meaning the Sieve is being evaluated by a 
Message Transfer Agent, "MDA", meaning evaluation is 
being performed by a Mail Delivery Agent, "MUA", 
meaning evaluation is being performed by a Mail User 
Agent, and "MS", meaning evaluation is being performed 
by a Message Store. Additional information and 
background on these terms can be found in 

[EMATL-ARCH] . 


The product name associated with the Sieve interpreter. 


The point relative to final delivery where the 

Sieve script is being evaluated. Possible values are 
"pre", "during", and "post", referring respectively to 
processing before, during, and after final delivery 
has taken place. 


Host name of remote SMTP/LMTP/Submission client 
expressed as a Fully Qualified Domain Name (FQDN), 

if applicable and available. The empty string will be 
returned if for some reason this information cannot be 
obtained for the current client. 
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"remote-ip" 
=> IP address of remote SMTP/LMTP/Submission client, if 
applicable and available. IPv4, IPv6, and other types 
of addresses are respectively represented in the 
formats defined by the IPv4-address-literal, 
IPv6-address-literal, and General-address-literal 
productions defined in Section 4.1.3 of [RFC2821]. 


"version" => The product version associated with the Sieve 
interpreter. The meaning of the product version string 
is product-specific and should always be considered 
in the context of the product name given by the 
"name" item. 


Implementations SHOULD support as many of the items on this initial 
list as possible. Additional standardized items can only be defined 


in standards-track or experimental RFCs. 


4.2. Vendor-defined Environment Items 


Environment item names beginning with "vnd." represent vendor-defined 
extensions. Such extensions are not defined by Internet standards or 
RFCs, but are still registered with IANA in order to prevent 
conflicts. 

4.3. IANA Registration of Environment Items 


A registry of environment items is provided by IANA. Item names may 
be registered on a first-come, first-served basis. 


Groups of items defined in a standards track or experimental RFC MAY 
choose to use a common name prefix of the form "name.", where "name" 
is a string that identifies the group of related items. 


Items not defined in a standards track or experimental RFC MUST have 
a name that begins with the "vnd." prefix, and this prefix is 
followed by the name of the vendor or product, such as 
"vnd.acme.rocket-sled-status". 
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4.3.1. Template for Environment Registrations 


The following template is to be used for registering new Sieve 
environment item names with IANA. 


To: iana@iana.org 
Subject: Registration of new Sieve environment item 


Item name: [the string for use in the ’environment’ test] 
Description: [a brief description of the semantics of the 
value the item returns] 


RFC number: [for extensions published as RFCs] 
Contact address: [email and/or physical address to contact for 
additional information] 
Multiple items and descriptions MAY be specified in a single 
registration request. Both standardized and vendor-defined items use 
this form. 


5. Security Considerations 


The environment extension may be used to obtain information about the 


system the Sieve implementation is running on. This information in 
turn may reveal details about service provider or enterprise 
infrastructure. 


An implementation can use any technique to determine the remote-host 
environment item defined in this specification, and the 
trustworthiness of the result will vary. One common method will be 
to perform a PTR DNS lookup on the client IP address. This 
information may come from an untrusted source. For example, the 
test: 


if environment :matches "remote-host" "*.example.com" { ... } 


is not a good way to test whether the message came from "outside" 
because anyone who can create a PTR record can create one that refers 
to whatever domain they choose. 


All of the security considerations given in the base Sieve 
specification also apply to this extension. 


Freed Standards Track [Page 5] 


RFC 5183 Sieve Environment Extension May 2008 


6. IANA Considerations 


The following template specifies the IANA registration of the Sieve 
extension specified in this document: 


To: iana@iana.org 
Subject: Registration of new Sieve extension 


Capability name: environment 

Description: The "environment" extension provides a new 
environment test that can be used to implement 
scripts that behave differently when moved 
from one system to another or otherwise 
operated in different contexts. 

RFC number: RFC 5183 

Contact address: Sieve discussion list <ietf-mta-filters@imc.org> 


This specification also defines a new IANA registry for Sieve 
environment item names. The specifics of this registry are given in 
Section 4.3. The initial contents of the registry are given in the 
following section. 
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6.1. Initial Environment Item Registrations 
The following template specifies the initial IANA registrations for 


the environment items defined in this document: 


To: 
Subject: 


Capability name: 
Description: 


Capability name: 
Description: 


Capability name: 
Description: 
Capability name: 


Description: 


Capability name: 
Description: 


Capability name: 
Description: 


Capability name: 
Description: 


Capability name: 
Description: 


RFC number: 
Contact address: 


iana@iana.org 
Registration of new Sieve environment items 


domain 

The primary DNS domain associated with the Sieve 
execution context, usually but not always a 
proper suffix of the host name. 


host 
The fully-qualified domain name of the host 
where the Sieve script is executing. 


location 
Type of service executing the Sieve script. 


name 
The product name associated with the Sieve 
interpreter. 


phase 
Point relative to final delivery at which the 
Sieve script is being evaluated. 


remote-host 
Host name of remote SMTP client, 
and available. 


if applicable 


remote-ip 
IP address of remote SMTP client, 
and available. 


if applicable 


version 
The product version associated with the Sieve 
interpreter. 


RFC 5183 
Sieve discussion list <ietf-mta-filters@imc.org> 
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